Crate mirror_mirror

General purpose reflection library for Rust.

Examples

Access a field by its string name and mutate it

use mirror_mirror::{Reflect, Struct};

#[derive(Reflect, Clone, Debug)]
struct Foo {
    x: i32,
}

let mut foo = Foo { x: 42 };

// Get a `Struct` trait object for `Foo`.
//
// The `Struct` trait has methods available for all structs such as accessing
// fields by name and iterating over the fields.
let struct_obj: &mut dyn Struct = foo.as_struct_mut()?;

// Mutably borrow the `x` field. We can access fields using string names.
let x: &mut dyn Reflect = struct_obj.field_mut("x")?;

// Downcast `x` into a mutable `i32`
let x: &mut i32 = x.downcast_mut::<i32>()?;

// Change the value of `x`
*x += 1;

// The value of `x` in `foo` has now changed.
assert_eq!(foo.x, 43);

Iterate over all fields

use mirror_mirror::{Reflect, Struct, ReflectMut, ScalarMut, enum_::VariantFieldMut};

// A function that iterates over the fields in an enum and mutates them.
fn change_enum_fields(value: &mut dyn Reflect) -> Option<()> {
    let enum_ = value.as_enum_mut()?;

    for field in enum_.fields_mut() {
        match field {
            VariantFieldMut::Struct(_, value) | VariantFieldMut::Tuple(value) => {
                match value.reflect_mut() {
                    ReflectMut::Scalar(ScalarMut::i32(n)) => {
                        *n *= 2;
                    }
                    ReflectMut::Scalar(ScalarMut::String(s)) => {
                        *s = format!("{s}bar");
                    }
                    // Ignore other types
                    _ =>  {}
                }
            }
        }
    }

    Some(())
}

#[derive(Reflect, Clone, Debug)]
enum Bar {
    X { x: i32 },
    Y(String),
}

let mut bar = Bar::X { x: 42 };
change_enum_fields(bar.as_reflect_mut())?;

assert!(matches!(bar, Bar::X { x: 84 }));

let mut bar = Bar::Y("foo".to_owned());
change_enum_fields(bar.as_reflect_mut())?;

assert!(matches!(bar, Bar::Y(s) if s == "foobar"));

Query value and type information using key paths

use mirror_mirror::{
    Reflect,
    key_path,
    key_path::{GetPath, GetTypePath, field},
    type_info::{DescribeType, ScalarType},
};

// Some complex nested data type.
#[derive(Reflect, Clone, Debug)]
struct User {
    employer: Option<Company>,
}

#[derive(Reflect, Clone, Debug)]
struct Company {
    countries: Vec<Country>,
}

#[derive(Reflect, Clone, Debug)]
struct Country {
    name: String
}

let user = User {
    employer: Some(Company {
        countries: vec![Country {
            name: "Denmark".to_owned(),
        }],
    }),
};

// Build a key path that represents accessing `.employer::Some.0.countries[0].name`.
//
// `::Some` means to access the `Some` variant of `Option<Company>`.
let path = field("employer").variant("Some").field(0).field("countries").get(0).field("name");

// Get the value at the key path.
assert_eq!(user.get_at::<String>(&path).unwrap(), "Denmark");

// Key paths can also be constructed using the `key_path!` macro.
// This invocation expands the same code we have above.
let path = key_path!(.employer::Some.0.countries[0].name);

// Use the same key path to query type information. You don't need a value
// of the type to access its type information.
let user_type = <User as DescribeType>::type_descriptor();
assert!(matches!(
    user_type.type_at(&path).unwrap().as_scalar().unwrap(),
    ScalarType::String,
));

Using opaque Value types

use mirror_mirror::{Reflect, Value, FromReflect};

#[derive(Reflect, Clone, Debug)]
struct Foo(Vec<i32>);

let foo = Foo(vec![1, 2, 3]);

// Convert `foo` into general "value" type.
let mut value: Value = foo.to_value();

// `Value` also implements `Reflect` so it can be mutated in the
// same way we've seen before. So these mutations can be made
// by another crate that doesn't know about the `Foo` type.
//
// `Value` is also serializable with `speedy`, for binary serialization,
// or `serde`, for everything else.
value
    .as_tuple_struct_mut()?
    .field_at_mut(0)?
    .as_list_mut()?
    .push(&4);

// Convert the `value` back into a `Foo`.
let new_foo = Foo::from_reflect(&value)?;

// Our changes were applied.
assert_eq!(new_foo.0, vec![1, 2, 3, 4]);

Inspiration

The design of this library is heavily inspired by bevy_reflect but with a few key differences:

• speedy integration which is useful for marshalling data perhaps to send it across FFI.
• A Value type that can be serialized and deserialized without using trait objects.
• More type information captured.
• Add meta data to types which becomes part of the type information.
• Key paths for querying value and type information.
• No dependencies on bevy specific crates.
• #![no_std] support.

Feature flags

mirror-mirror uses a set of [feature flags] to optionally reduce the number of dependencies.

The following optional features are available:

Name	Description	Default?
std	Enables using the standard library (core and alloc are always required)	Yes
speedy	Enables speedy support for most types	Yes
serde	Enables serde support for most types	Yes
glam	Enables impls for glam	No
macaw	Enables impls for macaw	No

Modules

• array
  Reflected array types.
• enum_
  Reflected enum types.
• get_field
  Helper traits for accessing fields on reflected values.
• iter
  Iterator types.
• key_path
  Key paths for querying value and type information.
• list
  Reflected list types.
• map
  Reflected map types.
• struct_
  Reflected struct types.
• try_visit
• tuple
  Reflected tuple types.
• tuple_struct
  Reflected tuple struct types.
• type_info
  Type information.
• value
  Type erased value types.

Macros

• key_path
  Convenience macro for creating KeyPaths.

Structs

• TypeDescriptor
  The root of a type.

Enums

• ReflectMut
  A mutable reflected value.
• ReflectOwned
  An owned reflected value.
• ReflectRef
  An immutable reflected value.
• ScalarMut
  An mutable reflected scalar value.
• ScalarOwned
  An owned reflected scalar type.
• ScalarRef
  An immutable reflected scalar value.
• Value
  A type erased value type.

Traits

• Array
  A reflected array type.
• DescribeType
  Trait for accessing type information.
• Enum
  A reflected enum type.
• FromReflect
  A trait for types which can be constructed from a reflected type.
• GetField
  Helper trait for accessing and downcasting fields on reflected values.
• GetFieldMut
  Helper trait for mutably accessing and downcasting fields on reflected values.
• List
  A reflected list type.
• Map
  A reflected map type.
• Reflect
  A reflected type.
• Struct
  A reflected struct type.
• Tuple
  A reflected tuple type.
• TupleStruct
  A reflected tuple struct type.

Functions

• reflect_debug
  Debug formatter for any reflection value.
• reflect_eq
  Compare two reflected values for equality.

Derive Macros

• Reflect
  Derive an implementation of Reflect and other appropriate traits.